Stabilize cargo script by epage · Pull Request #16569 · rust-lang/cargo

epage · 2026-01-30T14:32:38Z

RFC: https://rust-lang.github.io/rfcs/3502-cargo-script.html
Tracking issue: #12207
Frontmatter stabilization: rust-lang/rust#148051

This stabilizes an MVP of Cargo script

Cargo scripts are Rust source files without an extension or with a .rs extension
They may have a frontmatter block with manifest content
Changes from Cargo.toml
- package.name is optional, defaults to the file stem
- package.edition defaults to current edition, not 2015 edition, with a warning
- package.build, package.links, package.default-run, package.workspace, package.auto-* are disallowed
- workspace, build-dependencies, and any build-target tables are disallowed
- Workspace auto-discovery does not run
package.name defaulting logic
- strips leading numbers
  - If nothing left after this, calls it package
- replaces non-UnicodeXID characters with - or _
- commonly reserved names are allowed:
  - windows names, like con
  - sysroot names, like test
  - keywords, like self
- disallowed names on a short-term basis:
  - build-dir directories like deps
cargo foo precedence:
1. built-in command
2. script if there is a .rs extension or a path component is present (e.g. ./foo )
3. aliases
4. plugins
Command support:
- cargo install errors on publishing a script
- cargo package errors on publishing a script
- cargo publish errors on publishing a script
Script metadata
- arg0 is set on a best-effort basis to the script's path
- CARGO_MANIFEST_PATH was previously stabilized in addition to the existing CARGO_MANIFEST_DIR
cargo foo only loads config CARGO_HOME
- Regular cargo run loads from current dir
- Previous proposal was to load from scripts directory but there was concern over running scripts in a Downloads directory pulling in unexpected config

Pseudo-config defaults

[build]
build-dir = "{cargo-cache-home}/build/{workspace-path-hash}"
target-dir = "{build-dir}/target"
[resolver]
lockfile-path = "{build-dir}/Cargo.lock"

Whats missing:

rustfmt styling frontmatter according to the Style Guide
rust-analyzer handling manifest in frontmatter
playground support

Known issues:

cargo remove prints the "unset edition" warning twice
Some users are asking for reduced noise (Cargo script should only output messages from the script for no-change builds #16388)
Shebang stripping isn't as complete as rustc in that it only considers whitespace between #! and [] and not comments

Risks

If people share their build-dir across projects, then multiple scripts will point to the same Cargo.lock, fighting over what is locked in it
Not allowing local config for scripts could become a problem as we get into workspace support as people would expect their repo's config to be respected when it won't be
Changing package name rules impacts programmatic output
Precedence rules for cargo foo
- In particularly, requiring an extension or path element should be safe, especially for most uses of shebang but you can intentionally contrive a shebang and PATH that makes this not work

Future possibilities

Membership in workspaces including opt-in discovery (Less invasive way of controlling workspace membership #16563)
Publish support
Lib support
- main question is how to denote it is a lib
Build script delegation support (Tracking issue for RFC 2196, "metabuild: semantic build scripts for Cargo" #14903)
Use as artifact dependencies
GC build-dirs (Garbage collect whole target/ #13136)
Reduce special casing in manifests with Make package.name optional #12689
cargo Cargo.toml support

rustbot · 2026-01-30T14:32:43Z

r? @weihanglo

rustbot has assigned @weihanglo.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

epage · 2026-01-30T15:25:05Z

src/bin/cargo/commands/run.rs

+    match manifest_path.is_file() {
+        true => {}


Cleaned up in the next commit

epage · 2026-01-30T15:25:33Z

src/cargo/core/compiler/mod.rs

+    // TODO: remove once frontmatter hits nightly
    if unit.pkg.manifest().is_embedded() {


Blocked on rust-lang/rust#148051 hitting nightly

epage · 2026-01-30T15:25:39Z

src/cargo/core/compiler/mod.rs

+    // TODO: remove once frontmatter hits nightly
    if unit.pkg.manifest().is_embedded() {


Blocked on rust-lang/rust#148051 hitting nightly

src/bin/cargo/commands/run.rs

epage · 2026-01-30T15:39:45Z

@rfcbot fcp merge T-cargo

For me, my biggest concerns are the first two Risks listed.

rust-rfcbot · 2026-01-30T15:39:46Z

Team member @epage has proposed to merge this. The next step is review by the rest of the tagged team members:

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

weihanglo

Should we inform rustfmt team that we're going to stabilize this and leave frontmatter style issue unresolved? I remembered that let-else has caused confusions and frustrations when we stabilized it in the language syntax side but rustfmt didn't format it: rust-lang/rustfmt#4914.

At least the rustfmt team should be aware of the potential incoming volume of issues regarding this.

View changes since this review

weihanglo · 2026-01-31T11:46:57Z

src/doc/src/reference/manifest.md

 in the [TOML] format. It contains metadata that is needed to compile the package. Checkout
 the `cargo locate-project` section for more detail on how cargo finds the manifest file.

+The content of the manifest can also be embedded inside of the frontmatter inside of a Rust source file:


Not a blocker but not satisfied with the current stable doc. I would love to see a dedicated section for Cargo scripts with some examples, and all other mentions of "script" to link back to that section. Currently it is a bit not obvious when it is mentioned.

The original unstable docs has some good stuff in it but maybe it depends on many stuff we want to commit as "stable"

(Or it was migrated to elsewhere? The diff is too large that I could have missed it)

Was unsure how to handle it. A guide? If so, where does it fit in. A reference? Does it get its own page or a section on manifests?

Or a reference-like doc in src/doc/man/cargo.md, and we have another standalone guide? In manifest is not too bad but script is more than manifest.

weihanglo · 2026-01-31T12:08:32Z

rustfmt styling frontmatter according to the Style Guide

rust-analyzer handling manifest in frontmatter

playground support

All these teams actually

weihanglo · 2026-01-31T12:16:09Z

Pseudo-config defaults

This is worth calling out in user doc that whether the target directory of script is considered implementation details.

epage · 2026-01-31T14:08:29Z

Should we inform rustfmt team that we're going to stabilize this and leave frontmatter style issue unresolved? I remembered that let-else has caused confusions and frustrations when we stabilized it in the language syntax side but rustfmt didn't format it: rust-lang/rustfmt#4914.

At least the rustfmt team should be aware of the potential incoming volume of issues regarding this.

View changes since this review

This was handled as part of the Frontmatter stabilization.

src/bin/cargo/main.rs

weihanglo · 2026-01-31T15:16:37Z

src/doc/src/reference/manifest.md

 in the [TOML] format. It contains metadata that is needed to compile the package. Checkout
 the `cargo locate-project` section for more detail on how cargo finds the manifest file.

+The content of the manifest can also be embedded inside of the frontmatter inside of a Rust source file:


Or a reference-like doc in src/doc/man/cargo.md, and we have another standalone guide? In manifest is not too bad but script is more than manifest.

### What does this PR try to resolve? As found on #16569 ### How to test and review this PR?

This is to make space for discussing scripts, see rust-lang#16569

### What does this PR try to resolve? This is to make space for discussing scripts, see #16569 ### How to test and review this PR?

nicoburns · 2026-02-06T12:16:01Z

If we stabilise cargo foo shorthand, would that prevent further additions to that namespace in future?

This is subjective, but it feels to me like an "impl trait in argument position" situation where a more controversial extension of a feature is slipping into the stabilisation of an overwhelmingly popular feature.

I wonder whether it might be best to omit this from the initial stabilisation. cargo run foo.rs isn't that bad in the short term (but if there are no backwards compat hazards then I guess it's fine).

epage · 2026-02-06T12:27:11Z

cargo <path> requires either

<path> to have a .rs extension
<path> to have path separators

cargo run path

would be a breaking change as positional arguments get forwarded
would require a non-standard env extension, like -S

epage added 3 commits January 30, 2026 08:03

feat: Stabilize cargo script

4e8dcfb

refactor(cli): Simplify script logic

a71be8d

docs: Document cargo script

4284ce0

epage added the T-cargo Team: Cargo label Jan 30, 2026

rustbot assigned weihanglo Jan 30, 2026

epage marked this pull request as draft January 30, 2026 14:32

rustbot removed the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Jan 30, 2026

epage commented Jan 30, 2026

View reviewed changes

weihanglo reviewed Jan 30, 2026

View reviewed changes

src/bin/cargo/commands/run.rs Show resolved Hide resolved

epage force-pushed the script-stable branch from 9b5af41 to 4284ce0 Compare January 30, 2026 15:28

epage marked this pull request as ready for review January 30, 2026 15:39

rustbot added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Jan 30, 2026

rust-rfcbot added proposed-final-comment-period An FCP proposal has started, but not yet signed off. disposition-merge FCP with intent to merge labels Jan 30, 2026

epage mentioned this pull request Jan 30, 2026

Tracking issue for release notes of #148051: Stabilize Frontmatter rust-lang/rust#151840

Open

weihanglo reviewed Jan 31, 2026

View reviewed changes

epage mentioned this pull request Feb 2, 2026

fix(script): Correct style of help message #16580

Merged

github-merge-queue bot pushed a commit that referenced this pull request Feb 2, 2026

fix(script): Correct style of help message (#16580)

ce9aee0

### What does this PR try to resolve? As found on #16569 ### How to test and review this PR?

epage added a commit to epage/cargo that referenced this pull request Feb 2, 2026

docs(cli): Discuss commands and aliases

d8d3b59

This is to make space for discussing scripts, see rust-lang#16569

epage mentioned this pull request Feb 2, 2026

docs(cli): Discuss commands and aliases #16581

Merged

github-merge-queue bot pushed a commit that referenced this pull request Feb 3, 2026

docs(cli): Discuss commands and aliases (#16581)

1adc2c3

### What does this PR try to resolve? This is to make space for discussing scripts, see #16569 ### How to test and review this PR?

ehuss added this to Cargo status tracker Feb 3, 2026

ehuss moved this to FCP merge in Cargo status tracker Feb 3, 2026

traviscross mentioned this pull request Feb 6, 2026

Cargo script edition policy (lang/edition aspects) rust-lang/rust#152254

Open

		// TODO: remove once frontmatter hits nightly
		if unit.pkg.manifest().is_embedded() {

Conversation

epage commented Jan 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rustbot commented Jan 30, 2026

Uh oh!

epage Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

epage Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

epage Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

epage commented Jan 30, 2026

Uh oh!

rust-rfcbot commented Jan 30, 2026 • edited by arlosi Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

weihanglo left a comment • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

weihanglo Jan 31, 2026

Choose a reason for hiding this comment

Uh oh!

epage Jan 31, 2026

Choose a reason for hiding this comment

Uh oh!

weihanglo Jan 31, 2026

Choose a reason for hiding this comment

Uh oh!

weihanglo commented Jan 31, 2026

Uh oh!

weihanglo commented Jan 31, 2026

Uh oh!

epage commented Jan 31, 2026

Uh oh!

Uh oh!

weihanglo Jan 31, 2026

Choose a reason for hiding this comment

Uh oh!

nicoburns commented Feb 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

epage commented Feb 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

epage commented Jan 30, 2026 •

edited

Loading

rust-rfcbot commented Jan 30, 2026 •

edited by arlosi

Loading

weihanglo left a comment •

edited by rustbot

Loading

nicoburns commented Feb 6, 2026 •

edited

Loading